Cream of the Crop 12

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 12 / Cream of the Crop 12 (Part II) / Cream of the Crop 12 (Part II).iso / OS2 / SQTOOL06.ZIP / SqTool.Prn < prev next >

Wrap

Text File | 1996-03-28 | 87.3 KB | 2,564 lines

Le 28 mars 1996 à 17:24. SqTool (c) Raphaël Vanney The table of contents is at the end of the file. There is also an index down there. ---------------------------------------------------------------------- 1 Preliminary stuff ---------------------------------------------------------------------- 1.1 The disclaimer --------------------------------------------------------------------- I take no responsibility from whatever results from your use of SqTool. If you are not prepared to handle the consequences, please don't use SqTool. 1.2 What's SqTool ? --------------------------------------------------------------------- SqTool is meant to be a general-purpose utility for those of us who use Fidonet-style message bases. As of now, Squish and *.MSG bases are supported. If you run a BBS that uses Files.BBS files, SqTool can also provide file-oriented functions. Here are a couple things you can do with SqTool : . Filter messages to you, and copy them to a specified message area ; . Filter messages of interest, based on a keyword search, and copy them to a specified area ; . Remove messages you don't want on your system (for instance, messages which contain adult content on a children-dedicated BBS), or move them to a specified area ; . Select messages on their content, and generate automatic replies from a disk file ; . Trigger execution of external commands based on message content (ie when a specific subject is found, run a .CMD or .EXE file and return its output to the message sender) ; . Set up a mail-based file-request system ; . Automatically announce new files on your system ; . Automatically answer filefind requests ; . Build a listing of all files on your BBS ; . Import and export SOUP packets ; . etc... _________________________________________________ page 2 _________________________________________________ 1.3 SqTool & SqFilter --------------------------------------------------------------------- To those of you who used SqFilter : the source of SqFilter has been lost in a disk crash (always back up, they say...) Since I wanted to add features to SqFilter, I started rewriting it, et voilà, it's now called SqTool. Some of the features of SqFilter have been left out from SqTool. If you need some of them, or if you have a problem using SqTool replacement functions, please drop me a note (see "Support"). On the other hand, SqTool is now a 32-bit application (this does not mean a lot, except that it knows no memory constraints and runs a bit faster than SqFilter), and, tada!, it handles HPFS file names. You will also note that the filters capabilities have been enhanced, in ways I quite like. SqFilter configuration files won't directly plug into SqTool, but the areas and message filters definitions should not require too much work. 1.4 Support --------------------------------------------------------------------- SqTool is freeware, so don't expect professional-level, 24-hour support. Anyways, I usually answer requests for help and welcome enhancement requests. Of course, general comments or congratulations are welcome as well. Please feel free to drop me a note at one of the following addresses : . Internet rvanney@ibm.net . Fidonet 2:320/222.7 . Francomedia 101:173/209.7 Thanks to those who already did. Those of you who are willing to translate SqTool messages to another language are welcome (SqTool is designed to easily support other languages). I usually upload new versions of SqTool to the Hobbes ftp site (hobbes.nmsu.edu). _________________________________________________ page 3 _________________________________________________ 1.5 Credits --------------------------------------------------------------------- Thanks to David Ahia and Roland Gifford, who both tried to run SqTool despite its numerous bugs, and provided a number of enhancement suggestions. This documentation was typed in Microsoft Word 5.5, which is probably one of its last OS/2 applications. SqTool is written in SpeedPascal, and compiled using SpeedPascal/2 version 1.5 beta V. _________________________________________________ page 4 _________________________________________________ ---------------------------------------------------------------------- 2 Configuring SqTool ---------------------------------------------------------------------- SqTool operation is based on a configuration file, which contains several main parts : . Miscellaneous : various configuration options . Areas configuration : where you tell SqTool where and what your message and file areas are. . Filters configuration : where you tell SqTool what filters to apply. . FileFind configuration : if you want SqTool to act as an AllFix filefind request processor, you must provide SqTool some extra information. . SOUP configuration : if you want SqTool to import/export SOUP packets, you must provide a few details. The configuration file is named SqTool.Cfg, and must be stored in the same directory that holds the executable file (SqTool.Exe). This is a text file, which can be created and edited with any text editor. Empty lines and lines beginning with a ";" sign are ignored (use a ";" to insert a comment in the file). 2.1 Miscellaneous --------------------------------------------------------------------- AreasWrittenTo <filename> The AreasWrittenTo keyword lets you define a file where SqTool will put a list of all the message areas where it wrote a message. The typical use for this is to have a message tosser process these areas after SqTool has done its job. If the file already exists, SqTool appends data to it rather than overwriting it. Example : AreasWrittenTo c:\BBS\EchoToss.Log _________________________________________________ page 5 _________________________________________________ Debug Tells SqTool to generate much more verbose information in the log file. If you've got a misbehaviour (aka bug) to report, the debug log file often helps solve the problem. English Tells SqTool to use English messages (default when country code as specified in CONFIG.SYS is 1 (U.S.) or 44 (U.K.)). FidoUserNo <no> FidoUserNo tells SqTool which user number to use to store lastread information for Fido *.MSG message bases. See comments for "SquishUserNo". French Tells SqTool to use French messages (default when country code as specified in CONFIG.SYS is 33 or unknown). Include <filename> The Include keyword lets you include files in your configuration file. This might be handy if you use several configuration files and don't want to duplicate common information such as areas definition. You would then move the areas definition to another file and 'Include' this file in your main configuration files. The Include keyword may appear anywhere in the configuration file, except within a template text and filter definitions (where it would be considered as part of the text/filter). Nested include files are allowed, without any reachable limit. LockTimeOut <delay> Sets the maximum time SqTool will try to lock a message base. If a message base is kept locked by another process during more than this delay, SqTool will fail to lock it and halt with an error message. The delay is specified in thousands of a second. The default value is 10000 (ten seconds). Example : LockTimeOut 60000 _________________________________________________ page 6 _________________________________________________ Will try to lock a message base for up to one minute. LogSizeLimit <bytes> Defines the maximum size of the log file : it's such a PITA to have to shrink these log files periodically. SqTool will make sure that the log file does not grow over this size by removing older statements. Don't be surprised if one day the first line of your log file looks strange, SqTool does not check where it cuts the log file. The default value is 256kb. It can be set to anything between 1 and 2^31 bytes. Warning : the log file shrinking is quite a straight process : the program just moves the last LogSizeLimit bytes of the file to the beginning of the file, then truncates the file. This may be a lengthy process if your log file is 10Mb in size ! Though you can't disable this feature, setting this value high enough will prevent SqTool from shrinking the log file. MainAddress <address> Defines your main fidonet-like address, or aka. This address will be used when writing to message areas where no specific aka has been specified. MaxAnnPerMsg <number> Tells SqTool how many files, at most, may be announced in a single file announcement message (this relates to "Action Announce" in file filters). If more new files are to be announced, they will be separated over several messages. The default value is 100,000. ReScan Tells SqTool to ignore the lastread information and entirely rescan all message areas. SquishUserNo <no> SquishUserNo tells SqTool which lastread record it should use in the Squish *.SQL files. You should make sure that, if your reader uses this feature, it is set to use a different user no. The same applies if you run a BBS that uses the lastread information stored in Squish files. _________________________________________________ page 7 _________________________________________________ The default value for SquishUserNo is 0. You may use anything between 0 and 64k. UpperCaseFNames If this keyword is specified, file names written by file filters will be uppercased. The default is to write file names exactly as they appear in the FILES.BBS file. 2.2 Areas configuration --------------------------------------------------------------------- Areas may be defined either "manually" or using existing, other software's configuration files. 2.2.1 Manual message areas configuration Manual message areas definition uses the same syntax as GoldEd, the mail reader I use. Area <tag> "<description>" <base type><msg type> <base init str> <attr>[ <atr>...] where : <tag> short name for the message area ; this is the name you will use when referring to this area in SqTool configuration. <description> is an optional text describing the content of the area. <base type> may be either "M" (without the quotes) for Squish areas, or "F" for *.MSG areas. <msg type> May be "E" (without the quotes) for Echomail, "N"for NetMail, "L"for local areas. Defaults to Echomail. Note that there is no space between <base type> and <msg type>. <base init str> For Squish bases, path and file name without extension. For *.MSG bases, directory where the messages are stored. <attr> Default attributes of messages entered in this area. May be none, one or several of : . ARQ : _________________________________________________ page 8 _________________________________________________ . ATT : a file is attached . CFM : . CRA : crash mail . FRQ : file request . HLD : hold message . LOC : local (always set) . PVT : private message . SNT : sent . URQ : Example : Area OS2 "OS/2 main echo" ME e:\Msgs\OS2 AreaDef <tag> "<description>" <group> <msg type> <base type> <base init str> <aka> (<attr>) ["<origin>"] AreaDef has the same purpose than the Area keyword, but allows a more detailed configuration : <tag> See the "Area" keyword. <description> See the "Area" keyword. <group> Unused by SqTool (but must be present ; I suggest you use "*" (without the quotes)). <msg type> May be either "Net" (without the quotes) for NetMail messages, "Echo" for echomail messages, "Local" for local mail messages or "News" for newsgroups. <base type> May be either "Squish" (without the quotes) for Squish message bases, or "FTS1" for *.MSG bases. <base init str> See the "Area" keyword. <aka> Fidonet-style address (aka) to use when posting messages to this area. Use "." (a dot, without the quotes) to use your main address. _________________________________________________ page 9 _________________________________________________ <attr> See the "Area" keyword. Note that the brackets must be there even if no attribute is specified. <origin> Optional origin-line to use when writing messages in this area. Examples : AreaDef comp.os.os2.setup "UseNet : comp.os.os2.setup" * Echo Squish e:\Msgs\comp.os.os2.setup 999:320/222.7 () AreaDef MsgsToMe "Messages to or about me" * Echo Squish e:\Msgs\MsgsToMe 2:320/222.7 () AreaDef NetMail "NetMail" * Net Fido e:\Msgs\NetMail 2:320/222.7 (Pvt) (Note that the definition should NOT be split over several lines). 2.2.2 Automatic areas configuration SqTool can use several other-software configuration files to gather information relative to your areas. LoraPath <path> Tells SqTool where LoraBBS is installed. SqTool will use the files CONFIG.DAT, SYSMSG.DAT and SYSFILE.DAT in this directory to configure the message and file areas. See 4.2.3 for more details about Lora configuration files. AreasBBS <file name> Tells SqTool the name of a standard AREAS.BBS file where to find the message areas definition. Only Squish and *.MSG areas should be defined in this file. SquishCfg <file name> Tells SqTool the name of a Squish.Cfg file where to find the message areas definition. See 4.2.1 for more details about Squish.Cfg processing. 2.2.3 Manual file areas configuration Manual file areas configuration is done using the FileArea keyword. _________________________________________________ page 10 _________________________________________________ FileArea <tag> "<description>" <list name> <files path> <tag> short name for the file area ; this is the name you will use when referring to this area in SqTool configuration. <description> an optional description of the file area. <list name> the name of the file that contains the list of the files in the area. This file must comply to the Files.BBS format (see "Technical, gory details"). <files path> the path where the files may be found. Example : FileArea OS2Drv "OS/2 Drivers" e:\Lora\Files\OS2Drv\Files.BBS e:\Lora\Files\OS2Drv (Note that the definition should NOT be split over several lines). 2.3 Message filters configuration --------------------------------------------------------------------- The way SqTool process filters is, hopefully, apparent in the way a filter is defined : . SqTool scans the specified message base(s) ; . Each message in the base(s) is compared against the "triggering" criteria ; If the message matches the criteria (triggers the filter), the specified action is performed, and/or the specified reply is sent. A filter definition is made up of the following parts : 2.3.1. Filter header BeginFilter ["<description>"] BeginFilter starts the definition of a new filter. <description> is an optional description of the filter (this will help you identify the filter in the log file). _________________________________________________ page 11 _________________________________________________ 2.3.2 Definition of the areas to scan The following keywords define which areas should be scanned when processing this filter. You may use as many Scan and Unscan keywords as necessary. Scan <area_mask> <area_mask> is either the name (tag) of a previously defined message area or a group of areas, specified using the "*" wildcard. The "*" character may appear before or after the root name, but not in the middle of it. Examples : Valid : Scan os.os2.* Scan *.fr Scan *.os2.* Scan os2.fr Invalid : Scan rec.*.fr UnScan <area_mask> Tells SqTool NOT to scan the specified area(s), which supposedly have been previously selected by the "Scan" keyword. <area_mask> See the "Scan" keyword. Example : Scan comp.os.os2.* UnScan comp.os.os2.misc will scan all areas which's name (tag) starts with "comp.os.os2.", except the comp.os.os2.misc area. 2.3.3 Trigger The following keywords define what conditions trigger the filter. _________________________________________________ page 12 _________________________________________________ A filter may use several "Include" and "Exclude" keywords, which will be processed in the same order they appear in the configuration file. Include|Exclude [<operators>] "<ref_string>" Include trigger the filter if the message matches the condition that follows. Exclude un-trigger the filter if the message matches the condition that follows. <operators> are zero, one or several from : . Not negate the result of the search. . Exact perform an exact compare, rather than searching the reference string within the specified field(s). . Case : case-sensitive search. . From : search within the From field. . To : search within the To field. . Subject : search within the Subject field. . Header : search within the From, To and Subject fields. . Kludges : search within the kludge lines. . Message : search within the message text. . All : search within all the message fields, except kludges and addresses (this is the default). . Origin : compare to the originating address (Exact implicit). . Dest : compare to the destination address (Exact implicit). . QuotePct : check the percentage of quoted lines in the message against a specified range. There are three ways of specifying the range : ">n" (percentage must be greater than n), "<n" or "n-m" (percentage must be comprised between n and m). Blank lines, kludge lines, SEEN-BY, PATH, origin and tear lines are ignored. . And : the result of this search will be and'ed with the current trigger status. Not allowed in Exclude lines. _________________________________________________ page 13 _________________________________________________ . XOr : the result of this search will be xor'ed with the current trigger status. Not allowed in Exclude lines. . Or : the result of this search will be or'ed with the current trigger status (default). <ref_string> is the string that is to be searched in the message, or the quote percentage range. If the keyword "Origin" or "Dest" is used, this string should represent a valid FidoNet type address, where one or several of the fields may be replaced with a "*" to accept any value for this field. Examples : Include To Subject Message "Vanney" Exclude From "Vanney" The filter will be triggered if either the To field, the Subject field or the message text contain the string "Vanney", case-insensitively, except if the From field also contains this string. Include To Exact "Log Robot" Exclude Not Subject Exact "mypassword" The filter will be triggered if the To field is exactly (but case-insensitively) "Log Robot", and if the subject is equal to "mypassword". The same could be expressed as : Include To Exact "Log Robot" Include And Subject Exact "mypassword" Include Origin "2:320/222.*" Triggers the filter for any message coming from 2:320/222 and its points. Exclude QuotePct ">80" Prevents messages with more than 80% of quoted text from triggering the filter. 2.3.4 Action This keyword defines the action the filter should take when a message that matches the triggering conditions is encountered. _________________________________________________ page 14 _________________________________________________ Action <action> [params] <action> may be one of the following : Delete deletes the message. CopyTo <area_name> [Public] copies the message to the specified message area. If "Public" is specified, the PVT (private) attribute of the target message is cleared. MoveTo <area_name> [Public] moves the message to the specified message area. If "Public" is specified, the PVT (private) attribute of the target message is cleared. ForwardTo <area_name> [From "<author>"] forwards the message to the specified message area. You may optionally specify a string (<author>) that will be put in the "From" field of the forwarded message. Ack (function not implemented yet) Execute "<command>" shells to OS/2 and executes the <command>. See 4.4 for details. AllFix <result_file> Handles the message as a FileFind request, placing the result in the <result_file> file. See "FileFind configuration" for more details. AllFixMore <result_file> Handles the message as a FileFind second request, placing the result in the <result_file> file. See "FileFind configuration" for more details. 2.3.5. Reply The following keywords define the reply SqTool should make to the original message, after having performed the action. This is optional. _________________________________________________ page 15 _________________________________________________ ReplyWith <options> "<file_name>" Send the content of <file_name> as a reply to the message. If the file does not exist, no reply is sent. <option> is zero, one or several from : . uue : send the file uuencoded. Use this option to send binary files (binary files can't be sent as-is over mail ; UUE will convert them to a suitable text format. The receiver will need an uu-decoder to decode the file). . EAs : this option tells SqTool that the extended attributes of the file should be sent as well ; it is only meaningful when the "uue" option is used. . DelPrev : delete the file (if it exists!) before performing the action defined with the "Action" keyword. It is important to use the DelPrev option when the action is AllFix : if you don't, users that should not get an answer (no file found) will receive the answer to the previous successful request. . DelAfter : delete the file after sending the reply. ReplyArea <area_name> Send the reply in the specified message area (the default is to send the reply in the area where the message came from). ReplyAttr <attributes> Set the specified attributes to the reply message (by default, only the LOC attribute is set). See the "Area" keyword for a list of valid attributes. RepFooter Defines a text that will be inserted in the reply after the content of the file specified with ReplyWith. The text must end with a line containing the string "EndTxt" (without the quotes). When used in a filter which's action is AllFix, these header and footer are additive to those defined with AfxFoundHdr and AfxFoundFtr. _________________________________________________ page 16 _________________________________________________ ReplyFrom "<string>" SqTool will use <string> as the From field of reply messages for this filter. RepHeader Defines a text that will be inserted in the reply before the content of the file specified with ReplyWith. The text must end with a line containing the string "EndTxt" (without the quotes). 2.3.6 EndFilter EndFilter Terminates the definition of a filter. 2.3.7 Examples of filters BeginFilter "Messages about/to me" Scan comp.os.os2.* Include To Subject Message "Vanney" Exclude From "Vanney" Action CopyTo MsgsToMe EndFilter BeginFilter "Messages requesting the log file" Scan NetMail Include To Exact "Log Robot" Exclude Not Subject Exact "mypassword" ReplyWith "e:\Lora\Logs\Lora.Log" EndFilter BeginFilter "Offending messages" Scan comp.os.os2.* Include Message "Windows" Action Delete EndFilter _________________________________________________ page 17 _________________________________________________ BeginFilter "Externally handled messages" Scan robot.requests Include To "SqTool robot 2:320/222.7" Exclude Subject "help" Action Execute "e:\Stuff.Cmd" ; The reply is not generated if the file ; e:\Temp\Result.Txt does not exist. It is up to ; Stuff.Cmd to delete it if no reply should be ; made. ReplyWith "e:\Temp\Result.Txt" ReplyArea NetMail ; set the Crash and Private attributes to keep ; the answer confidential ReplyAttr CRA PRV EndFilter BeginFilter "Automatically reply to help requests" Scan robot.requests Include To Exact "SqTool robot 2:320/222.7" Include And Subject "help" ReplyWith "e:\PreparedMessages\RobotHelp.Txt" EndFilter BeginFilter "Let's get funny" Scan alt.binaries.pictures.for.teenagers Include From "aol.com" Include And Message "me too" ReplyWith e:\PreparedMsgs\StopSendingMeToos.Txt EndFilter _________________________________________________ page 18 _________________________________________________ 2.4 File filters configuration --------------------------------------------------------------------- The way file filters operate is somehow different from the message filters : - SqTool scans the specified file areas, and build a list of selected files ; - The specified action is then applied to the list of files that was built. A file filter definition is made up of the following parts : 2.4.1. Filter header BeginFileFilter ["<description>"] BeginFileFilter starts the definition of a new file filter. <description> is an optional description of the filter (this will help you identify the filter in the log file). 2.4.2 Definition of the areas to scan The following keywords define which file areas should be scanned when processing this filter. You may use as many Scan and Unscan keywords as necessary. Scan <area_mask> <area_mask> is either the name (tag) of a previously defined file area or a group of areas, specified using the "*" wildcard. The same rules as defined when Scan is used in message filters apply. UnScan <area_mask> Tells SqTool NOT to scan the specified area(s), which suposedly have been previously selected by the "Scan" keyword. <area_mask> See the "Scan" keyword. Example : Scan OS2* UnScan OS2Tools _________________________________________________ page 19 _________________________________________________ will scan all file areas which's name (tag) starts with "OS2", except the OS2Tools file area. 2.4.3 Select The following keyword define which files qualify for this filter. Select All|New New only new files will be processed. All all the files will be processed. SqTool considers file areas much like message areas. This means that, for SqTool, a "new" file is any file that has not been previously scanned. Thus, the first time you run SqTool to process a file filter, ALL files will be considered new, and processed as such. Example : Select New Will select all the new files for processing by this filter. 2.4.4 Action This keyword defines the action the filter should perform on the selected files. Action <action> <params> <action> may be one of the following : List will create a list of all the selected files into a text file. In this case, <param> is the name of the file where the list will be written. Announce will create a message set containing the list of the selected files. <param> is the name of a message area where the message will be sent. If no file is selected, the filter does nothing (ie SqTool does not make empty messages when there is nothing to announce). 2.4.5. Presentation The following keywords define the presentation of the message or the file SqTool will generate. _________________________________________________ page 20 _________________________________________________ Header Following the Header keyword is a text that will be inserted on top of the file listing. The text ends with the keyword "EndTxt" alone in a line. Example : Header Here is the list of the new files on Zlika : EndTxt Here is another way to get the same result : Header "Here is the list of the new files on Zlika :" EndTxt Footer Following the Footer keyword is a text that will be inserted at the bottom of the file listing. The text ends with the keyword "EndTxt" alone in a line. Example : Footer These files may be freely downloaded from Zlika. --- SqTool EndTxt or Footer "These files may be freely downloaded from Zlika." "--- SqTool" EndTxt From "<sender>" Defines the string that will be put in the From field of announcement messages. This keyword is useless when the Action is not Announce. _________________________________________________ page 21 _________________________________________________ To "<recipient>" Defines the string that will be put in the To field of announcement messages. This keyword is useless when the Action is not Announce. Subject "<subject>" Defines the string that will be put in the Subject field of announcement messages. This keyword is useless when the Action is not Announce. 2.4.6 EndFilter EndFilter Terminates the definition of a filter. 2.4.7 Examples of filters BeginFileFilter "Announce new files" Scan * UnScan UserUploads Select New Action Announce NewFiles Header "Here is a list of new files on the BBS :" EndTxt Footer "All these files are available for download." EndTxt Subject "New files on Zlika!" From "SqTool" To "All users" EndFilter This filter will announce all new files in the defined file areas, except those in the file area "UserUploads", to the NewFiles message area. _________________________________________________ page 22 _________________________________________________ BeginFileFilter "Make a listing of all files" Scan * UnScan UserUploads Select All Action List e:\Lora\Files\AllFiles.Lst Header "List of all the files available on Zlika." EndTxt Footer " -+-" "All these files may be freely downloaded." "Zlika is open from 10am to 6pm, on weekdays." "Phone number : +33-1-47748723" " -+-" "This file listing was built by SqTool." EndTxt EndFilter This filter will build a listing of all the files on the system in the file "e:\Lora\Files\AllFiles.Lst". BeginFileFilter "User uploads" Scan UserUploads Select New Action Announce SysAdmin Subject "Files recently updated by the users" EndFilter This filter will announce all the new files in the UserUploads file area with a message in the SysAdmin message area. 2.5 FileFind configuration --------------------------------------------------------------------- The following configuration options are necessary when using the "Action AllFix" and "Action AllFixMore" options in message filters. _________________________________________________ page 23 _________________________________________________ 2.5.1 File areas to scan AfxScan <area_mask> AfxScan tells SqTool which file areas should be scanned in search for files when answering to an AllFix filefind request. <area_mask> is either the name (tag) of a previously defined file area or a group of areas, specified using the "*" wildcard. The "*" character may appear before or after the root name, but not in the middle of it. AfxUnScan <area_mask> Tells SqTool which file areas NOT to scan among those previously selected with AfxScan. You may use as many AfxScan and AfxUnscan keywords as needed. 2.5.2 Answer setup The following keywords configure the answer message that will be sent if SqTool finds files in response to a filefind request. AfxFoundHdr This keyword is followed by a text that will be inserted on top of the answer message. The text is terminated by the keyword "EndTxt". Example : AfxFoundHdr The following file(s) were found on Zlika BBS : EndTxt AfxFoundFtr This keyword is followed by a text that will be inserted at the bottom of the answer message. The text is terminated by the keyword "EndTxt". Example : _________________________________________________ page 24 _________________________________________________ AfxFoundFtr "> Zlika BBS, an OS/2-oriented BBS" "SysOp : Raphaël Vanney" "Phone : +33-1-47748723" "Open hours : 10h00 - 19h00" EndTxt AfxMaxAnswers <number> Defines the maximum number of files that will be listed in an answer to a filefind request. The default is 20. AfxMaxDescLines <number> Defines the maximum description lines per file. The default is 10. 2.5.3 Example of FileFind setup ; define file areas where to search files AfxScan OS2* AfxScan DOS* AfxScan Divers ; define answer message header AfxFoundHdr The following file(s) were found on Zlika BBS : EndTxt ; define answer message footer AfxFoundFtr > Zlika BBS, an OS/2-oriented BBS SysOp : Raphaël Vanney Phone : +33-1-47748723 Open hours : 10h00 - 19h00 EndTxt ; define filter for first requests _________________________________________________ page 25 _________________________________________________ BeginFilter "Process FileFind requests" Scan wanted.fr Include To Exact "AllFix" Include To Exact "SqTool" Include To Exact "SqFltr" Action AllFix e:\Temp\AllFix.Res ReplyWith DelPrev DelAfter e:\Temp\AllFix.Res EndFilter ; define filter for requests for more files BeginFilter "Process FileFind second requests" Scan wanted.fr Include To Exact "AllFix 2:320/222.7" Include To Exact "SqTool 2:320/222.7" Include To Exact "SqFltr 2:320/222.7" Action AllFixMore e:\Temp\AllFix.Res ReplyWith DelPrev DelAfter e:\Temp\AllFix.Res EndFilter _________________________________________________ page 26 _________________________________________________ 2.6 The SOUP interface --------------------------------------------------------------------- The SOUP (Simple Offling Usenet Packet) format is an increasingly popular format used for offline newsgroups and mail reading. SqTool can import and export SOUP packets to and from your Fidonet message bases. SoupEMail <area> Tells SqTool in which message area it should put SOUP e-mail packets. SoupExportPath <path> Tells SqTool in which directory it should place the files exported for SOUP. If this variable is not defined, SqTool does not perform SOUP export. IMPORTANT : if you are already using a SOUP scanner and plan to replace it with SqTool, please note that it is not impossible that your current scanner and SqTool use a different method for tagging messages that have been scanned. If this is the case, SqTool will export _all_ messages from you the _first_ time it exports your SOUP newsgroups. You should then delete the files "Replies", "SqTNews.Msg" and "SqTMail.Msg" in your SoupExportPath directory. Other SOUP scanners also frequently use fake gateway addresses for importing/exporting SOUP packets. All references to these fake addresses must be removed or Squish will continue to export messages for the old gateway address. SoupImportPath <path> Tells SqTool where to look for a SOUP packet to be imported. If this variable is not defined, the SOUP import function is disabled. SoupNewsrcFile <file_name> Tells SqTool the name of your newsrc file. This file should contain the list of newsgroups you are connected to. SqTool uses it to know which message bases it should scan when exporting SOUP packets. _________________________________________________ page 27 _________________________________________________ ---------------------------------------------------------------------- 3 Running SqTool ---------------------------------------------------------------------- Installing SqTool is pretty straightforward : just copy the files in the archive to a directory. The following files are needed to run SqTool : SqTool.Exe, KBDVIO32.DLL and SqToolFr.Msg (French messages) or SqToolEn.Msg (English messages). Before running SqTool, you must create a suitable SqTool.Cfg configuration file. If you're not sure what a SqTool.Cfg file should look like, please take a look at the included SqTool.1st file, and build your own file after it, with the help of this documentation. The first time you run SqTool, you might want to use the "- InitPtr" command-line option. This will pre-set pointers so that SqTool does not scan all your messages and files bases. SqTool should be run periodically, for instance once a day, or each time you insert messages in your message bases (after a poll to your uplink). 3.1 Command-line options --------------------------------------------------------------------- SqTool recognizes the following command line parameters : -Debug Activates the debug mode. SqTool will generate a much more verbose log file. -ReScan Tells SqTool to rescan all MESSAGE areas, ignoring lastread information. -InitPtr Runs SqTool in a special mode, in which it will not proceed the filters but initialize the lastread information for all areas. This option should only be used once, the first time you run SqTool, so that it does not process all your messages and files (consider them as "new", or "unscanned") the first time it processes filters. It's pretty much the opposite of the "- ReScan" option. _________________________________________________ page 28 _________________________________________________ -Idle Runs SqTool at a low priority level. -Log=<log_file_name> Tells SqTool to use <log_file_name> as a log file, instead of the default SqTool.Log. -NoFileFlt Tells SqTool not to process file filters. Ignored when "- InitPtr" is used at the same time. -NoMsgFlt Tells SqTool not to process message filters. Ignored when "- InitPtr" is used at the same time. 3.2 Troubleshooting --------------------------------------------------------------------- 3.2.1 Run-Time Error 216 This is a serious error, which means SqTool has encountered a situation I had not planned. Though there are potentially many reasons for this error, I have spotted one on my system : using the TRIOS2.ADD driver (replacement for IBM1S506.ADD for TRITON-chipset motherboards) causes seemingly random Run-Time Error 216, which do not appear when using the stock IBM1S506.ADD. If you encounter such an error and are using a replacement IDE disk driver, please try replacing it with IBM1S506.ADD before reporting the error to me. 3.2.2 Error codes Under certain circumstances, most often due to a problem accessing a file, SqTool may stop with a message indicating an error number. Here's a list of error numbers and their meaning : OS/2 error codes 15 An invalid drive was specified. Check the path of the file you try to use. 32 Sharing violation. The file SqTool tried to gain exclusive access to is already locked by _________________________________________________ page 29 _________________________________________________ another process. Stop that process, or retry later. 110 A file was not found. This error may happen if the files needed by SqTool (*.Msg, *.Cfg) are not in the current directory. SqTool error codes 1000 You should never encounter this error ; it means SqTool has attempted writing to a message base without locking it first. Please report if you see it happen. 2000 (Squish) The index file is too small when compared to the number of messages indicated in the base header. The base needs be fixed. 2001 (Squish) The end_frame field of the header is incorrect. The base needs be fixed. 2002 (Squish) The num_msg and high_msg fields are different, while they should always be equal. The base needs be fixed. 2003 (Squish) The value of the sz_sqhdr field is not what was expected. If you systematically encounter this error, it means that the version of Squish that was used to create the message base is different of the one I know of, and incompatible with it. This should not happen until the Squish format is seriously changed by its author. 2004 (Squish) A frame was not identified as such, due to an invalid Id. The base needs be fixed. 2005 (Squish) An unknown frame_type was encountered. Either the base is damaged, or the format is incompatible with the Squish 2.00 API. 2006 (Squish) This error should not happen. It means that SqTool has tried to read a message that does not exist. 3001 (*.MSG) This is the same as 2006, but for *.MSG bases. _________________________________________________ page 30 _________________________________________________ ---------------------------------------------------------------------- 4 Technical, gory details ---------------------------------------------------------------------- 4.1 UUEncode and extended attributes --------------------------------------------------------------------- As far as I know, the UUEncode "standard" does not make any provision to uuencode extended attributes, so I decided to make my own. When using the "uue EAs" options of the ReplyWith keyword, SqTool builds and uuencoded file which contains two files, each enclosed in its own pair of "begin"/"end" statements. The first file contains the actual source file, the second file its extended attributes. The second file is named "EAs.for.<filename>", where <filename> is the name of the main file. Depending on the decoder used to retrieve the file, the result is as follows : . If the decoder does not handle several files in one archive, it will create the original file without the extended attributes. . If the decoder does handle multiple files in one archive, but does not handle HPFS file names, the result is unknown to me ; the main file will be decoded, but there will be a problem with the EA's file. . If the decoder handles multiple files in one archive and knows about HPFS, it will create two files, the main file and the EAs file. If the target file system is HPFS, the EA's file name will be as indicated earlier, otherwise unknown to me. Anyways, the user will then be able to reinstate the extended attributes with the EAUtil.Exe command (comes with OS/2). . If you use my own uu-decoder, the file will be automatically decoded with its extended attributes. My decoder is freeware and should be available from hobbes.nmsu.edu as UUCode??.Zip (current version is UUCode13.Zip). 4.2 Foreign configuration files --------------------------------------------------------------------- SqTool supports some of the popular BBS configuration files. If you would like SqTool to support another configuration file format, please get in touch with me (see "Support"). _________________________________________________ page 31 _________________________________________________ 4.2.1 Squish.Cfg The following keywords are recognized in a Squish.Cfg configuration file : Address Your main Fidonet address. AreasBBS The name of an Area.BBS file. NetArea Definition of a Netmail area. EchoArea Definition of an Echomail area. LocalArea Definition of a local area. Only the "-f", "-p" and "-$" flags of area definitions are used by SqTool. 4.2.2 Areas.BBS The following information is retrieved from an Areas.BBS configuration file : . All Squish and *.MSG message areas configuration. Areas are assumed to be of Echomail type. The alias (aka) is not used, since it does not appear to be accurate for point systems. 4.2.3 LoraBBS The following information is retrieved from LoraBBS configuration files : . All Squish and Fido (*.MSG) message areas configuration, including Aka, description and origin line ; . All file areas, except those that don't have a short name defined : YOU MUST DEFINE A SHORT NAME with Lora's configuration program if you want SqTool to use the file areas. The short name of file areas is the equivalent of the "Echo-tag" for message areas. 4.2.4 Files.BBS Files.BBS files are text files containing a list of files and their descriptions. They are used by many BBS softwares to store a list of files in a file area. However, there does not appear to be any real standard format for this file. SqTool will understand any file that follow these rules : _________________________________________________ page 32 _________________________________________________ . a line that begins with one or several characters " " (space), ">", "<" or "+" will be considered as an extended description line. Any line that does not begin with one of these characters will be considered as a "normal" line. . a normal line contains a file name, a space, then a description for the file. This means that no file name should contain a space. . empty lines are ignored. Example of a valid Files.BBS file : Dial153.zip Dialer v1.53, beta FWADP28.ZIP This is the patched FAX.ADP file for >Faxworks Lite and the USR Sportster >28800 FAX Modems. ic10390.zip Correctif pour OS/2 Warp Connect/MPTN >\mptn\protocol\afinet.sys >\mptn\bin\inetcfg.exe web103.zip WebExplorer V1.03 WKICKR.ZIP Corrective Service Facility disks for >installing OS/2 FixPaks. 4.3 FileFind requests processing --------------------------------------------------------------------- SqTool accepts the same request syntax as defined by Allfix, including handling of boolean operations defined with "And", "Or" and "XOr". SqTool being HPFS-aware, a request such as : "*abc*def*" is valid and would return any file which's name contains the strings "abc" and "def", in this order. _________________________________________________ page 33 _________________________________________________ 4.4 External execute --------------------------------------------------------------------- This section relates to the "Execute" option of the "Action" keyword of message filters. The process may use (retrieve) the following environment variables : . MsgFrom "from" field of the message . MsgTo "to" field of the message . MsgSubject "subject" field of the message . MsgOrigin origin address of the message . MsgDest destination address of the message . MsgWritten date at which the message was written . MsgBody The name of a temporary file where SqTool has stored the message content (without header information). Note that invalid characters ("@", "=", control characters) will be replaced with a "*" when setting the environment variables. This is important to keep in mind if your filter processes messages with Internet addresses in the header (the "@" of the Internet address will be replaced with a "*"). The process will always be executed through the command processor (as defined by the COMSPEC environment variable). The "Execute" option is a very powerful one, which enables you to do virtually anything through mail, specially when used together with REXX scripts. Beware, however, that this might be a widely open security hole. Imagine what could be done with a filter such as : BeginFilter Scan NetMail Include To "Executor" Action Execute "%MsgSubject% >c:\Execute.Res" ReplyWith DelPrev DelAfter "c:\Execute.Res" ReplyAttr Cra EndFilter This filter, when it encounters a message to "Executor" in the NetMail area, executes the command specified in the Subject field of the message and crash-replies with the output of the command. _________________________________________________ page 34 _________________________________________________ 4.5 The SOUP format --------------------------------------------------------------------- The soup format documentation is available from Rhys Weatherley at "rhys@cs.uq.oz.au" (well, so says the doc). SqTool (partly) supports version 1.2 of the SOUP format. Within this specification, the following message file formats are handled : . u (import) USENET news articles . m (import) Unix mail . b (export) Binary mail . B (export) Binary news Please drop me a note if you think others should be supported as well. SqTool only uses the files AREAS and *.MSG when tossing a SOUP packet. _________________________________________________ page 35 _________________________________________________ ---------------------------------------------------------------------- History ---------------------------------------------------------------------- 0.2 first public beta. 0.3 Added support for the FileFind requests processor. The "LoraBBS" keyword now reads file areas configuration. Added keywords "AfxScan", "AfxUnscan", "AfxFoundHdr", "AfxFoundFtr", "AfxMaxDescLines", "AfxMaxAnswers", "FileArea". Implemented "Action AllFix", added "Action AllFixMore". Fixed a bug with Scan and Unscan wildcard handling. Implemented the "Include" keyword (when used outside a filter). Fixed a number of various bugs. Added the file filters features (which replace SqFilter's new file announce and all files lister features). 0.4 Fixed a bug when an empty line follows a "BeginFilter" keyword. Added the "From", "To" and "Subject" keywords to file filters definitions. Added the "AreasWrittenTo" keyword. Added the command-line options "-Debug", "- InitPtr" and "-ReScan". The documentation (SqTool.Prn) should now have form-feed characters where appropriate (if not, replace all occurrences of the string "< TOPOFPAGE >" with a form-feed :-)). 0.5 (Feb 96) Added the "-Idle", "-NoFileFlt" and "-NoMsgFlt" command-line options. "LocalArea" keyword now recognized in Squish.Cfg. Added the "ForwardTo" action to message filters. Changed the behavior when "Area" or "AreaDef" define an already defined message base : the _________________________________________________ page 36 _________________________________________________ old definition is now replaced with the new one. A warning message is still issued. Added the "LockTimeOut" keyword. Added "RepHeader" and "RepFooter" keywords to message filters. SqTool now always sets the MSGID kludge line when the origin of the message is known. Added the "From" option to the "ForwardTo" action. Added the "MaxAnnPerMsg" keyword. Sped-up the file-areas related code. Added the "UpperCaseFNames" keyword. Now retrieves origin lines from .SQO files. 0.6 Fixed a problem with external execute when a field of the message contains invalid characters ("@", "="...). Added the "QuotePct" keyword. Added the "/LOG=" command-line parameter. Added support for SOUP packets. "SoupEMail", "SoupImportPath", "SoupExportPath", "SoupNewsrcFile" keywords. Fixed a bug handling Squish messages with an empty control area. Now correctly sets the DateWritten field to 0 for Squish locally entered messages. Added the ability to enclose texts in quotes (") within configuration files, which should help keep them readable (see the new headers/footers definitions in SqTool.1st). SqTool.Exe and KbdVio32.DLL are now compressed using LxLite by Andrew Zabolotny. _________________________________________________ page 37 _________________________________________________ ---------------------------------------------------------------------- Index ---------------------------------------------------------------------- *.MSG 6, 8, 9 .SQO 37 Ack 15 Action 15, 20, 34 Address 7, 9, 14, 32 AfxFoundFtr 16, 24 AfxFoundHdr 16, 24 AfxScan 24 AfxUnScan 24 Aka 7, 9 All 13, 20 AllFix 15, 16, 23, 24 AllFixMore 15, 23 And 13 Announce 7, 20 Area 8 AreaDef 9 Areas 8 Areas definition 6 AREAS.BBS 10, 32 AreasBBS 10, 32 AreasWrittenTo 5 ARQ 8 ATT 9 Attr 8, 10 Attribute 10, 16 Base type 8, 9 BeginFileFilter 19 BeginFilter 11 Binary 16 Case 13 CFM 9 Command line 28 COMSPEC 34 CONFIG.SYS 6 Configuration file 5, 6, 8 CopyTo 15 Country 6 CRA 9 Debug 6, 28 DelAfter 16 Delete 15 DelPrev 16 Dest 13 EAs 16, 31 EchoArea 32 Echomail 8, 9 EndFilter 17, 22 EndTxt 17, 21 _________________________________________________ page 38 _________________________________________________ English 6 Environment variable 34 Exact 13 Exclude 13 Execute 15, 34 Extended attribute 16, 31 FidoUserNo 6 File area 10, 32 File filters 19 FileArea 11 FileFind 15, 24 Files.BBS 32 Filters 11 Footer 21 ForwardTo 15 French 6 From 13, 15 FRQ 9 FTS1 9 GoldEd 8 Header 13, 21 HLD 9 Idle 29 Include 6, 13 InitPtr 28 Installing 28 Kludges 13 Language 3 Lastread 6, 7 List 20 LOC 9 Local 8, 9 LocalArea 32 LockTimeOut 6 Log 7, 29 LogSizeLimit 7 LoraBBS 10, 32 LoraPath 10 MainAddress 7 MaxAnnPerMsg 7 Message 13 MoveTo 15 Msg type 8, 9 MsgBody 34 MsgDest 34 MsgFrom 34 MsgOrigin 34 MsgSubject 34 MsgTo 34 MsgWritten 34 NetArea 32 NetMail 8, 9 New 20 _________________________________________________ page 39 _________________________________________________ Newsgroups 9 NoFileFlt 29 NoMsgFlt 29 Not 13 Operators 13 Or 14 Origin 10, 13 Origin-line 10 Percentage 13 Public 15 PVT 9, 15 Quoted lines 13 QuotePct 13 Range 13 RepFooter 16 Reply 15 ReplyArea 16 ReplyAttr 16 ReplyFrom 17 ReplyWith 16, 31 ReScan 7, 28 Scan 12, 19 Select 20 Short name 32 Shrink 7 SNT 9 SoupEMail 27 SoupExportPath 27 SoupImportPath 27 SoupNewsrcFile 27 SqFilter 3 SqTool.1st 28 SqTool.Cfg 5, 28 Squish 8, 9 Squish.Cfg 10, 32 SquishCfg 10 SquishUserNo 7 Subject 13 Support 3 Tag 8, 9, 11, 12, 19, 20, 24 To 13 Trigger 12, 14 TRIOS2.ADD 29 UnScan 12, 19 UpperCaseFNames 8 URQ 9 Uue 16, 31 Uuencode 16, 31 Wildcard 12, 19, 24 XOr 14 _________________________________________________ page 40 _________________________________________________ ---------------------------------------------------------------------- Table of contents ---------------------------------------------------------------------- 1 Preliminary stuff...............................2 1.1 The disclaimer 2 1.2 What's SqTool ? 2 1.3 SqTool & SqFilter 3 1.4 Support 3 1.5 Credits 4 2 Configuring SqTool..............................5 2.1 Miscellaneous 5 2.2 Areas configuration 8 2.2.1 Manual message areas configuration 8 2.2.2 Automatic areas configuration 10 2.2.3 Manual file areas configuration 10 2.3 Message filters configuration 11 2.3.1. Filter header 11 2.3.2 Definition of the areas to scan 12 2.3.3 Trigger 12 2.3.4 Action 14 2.3.5. Reply 15 2.3.6 EndFilter 17 2.3.7 Examples of filters 17 2.4 File filters configuration 19 2.4.1. Filter header 19 2.4.2 Definition of the areas to scan 19 2.4.3 Select 20 2.4.4 Action 20 2.4.5. Presentation 20 2.4.6 EndFilter 22 2.4.7 Examples of filters 22 2.5 FileFind configuration 23 2.5.1 File areas to scan 24 2.5.2 Answer setup 24 2.5.3 Example of FileFind setup 25 2.6 The SOUP interface 27 3 Running SqTool.................................28 3.1 Command-line options 28 3.2 Troubleshooting 29 3.2.1 Run-Time Error 216 29 3.2.2 Error codes 29 4 Technical, gory details........................31 4.1 UUEncode and extended attributes 31 4.2 Foreign configuration files 31 _________________________________________________ page 41 _________________________________________________ 4.2.1 Squish.Cfg 32 4.2.2 Areas.BBS 32 4.2.3 LoraBBS 32 4.2.4 Files.BBS 32 4.3 FileFind requests processing 33 4.4 External execute 34 4.5 The SOUP format 35 History........................................36 Index..........................................38 Table of contents..............................41 _________________________________________________ page 42 _________________________________________________